Amiga Tools 2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 2 / Amiga Tools 2.iso / tools / mg / docs / amiga next >

Wrap

Text File | 1995-03-09 | 29KB | 712 lines

Amiga MG 3Beta4 Release Notes ------------------------- This file attempts to document the Amiga-specific features of MG 2a. Except where otherwise noted. It is assumed that you already know about the point and the mark, buffers, windows, extended commands, and the various areas on the screen that all versions of MG maintain. If you don't, see the MG documentation (what there is of it) for more information. Amiga Credits ------------- The Amiga Intuition terminal driver is the combined effort of Mike Meyer and Mic Kaczmarczik. Others who helped and/or inspired good ideas for the MG terminal driver include Steve Walton, Leon Frenkel, Marcus Brooks, and Tom Rokicki. Steve Walton is also responsible for the dired mode. Bob Larson redesigned the MG keymap system, making it possible for function keys and mouse clicks to be ``first-class citizens''. Lastly, Mike Meyer added the Rexx support and redesigned the MG keymap & macro facilities, adding named keyboard macros and making them first-class objects. OPTIONS ------- This section is for people who have their own C compiler. If you don't have a C compiler, you will hopefully have a version that has everything compiled into it. There are a bewildering variety of extra goodies available as compile-time options when you construct an Amiga MG. If you select none of them, you save on disk and memory space, but lose out on some features and versatility. The config files provides documentation on these options and what to do to make them work. Read those and the documentation on config for descriptions on them. For those without ARexx (required to use the config program), the directory for the fully-featured configuration (Burrito) has been provided. The documentation for config should provide enough information to allow you to edit the include files by hand to create any version you wish to build. THE MOUSE --------- The Amiga Mouse can invoke no less than 24 different functions. Mouse clicks are essentially treated as keys by the MG, even though you click the mouse and hold down qualifier keys to get them. Mouse keys come in three groups of eight, the groups being: Mouse keys -- when clicked in the text of a window Mode-Mouse keys -- when clicked on a window's mode line Echo-Mouse keys -- when clicked in the echo area Inside each group, which of the eight keys you get is determined by the combination of Shift, CTRL and ALT keys you are holding down when the mouse button is pressed. So yes, there really is a Ctrl-Meta-Shift-Mode-Mouse button. Note that the Meta (M-) prefix *MUST* be the ALT key. Prefixing a mouse click with ESC will not work. Mouse keys are generally bound to functions that affect the text in the selected buffer. If the Intuition mouse pointer is located inside an MG text window (i.e. an area where text is being edited), then a Mouse key is sent to the editor when you click the mouse. The buffer associated wth the window the pointer is in is made current, point is set as close as possible to the pointer (the character under the pointer, if possible), then the command bound to that mouse button is executed. If the mouse pointer is in the mode line - the line that is in a different typeface (usually backlit, maybe black instead of white) -- when the mouse button is clicked, a Mode-Mouse key is sent to the editor. The buffer that the selected status line is associated with is made the current buffer, the point is set to the value of point for that window, then whatever command is bound to that button is executed. Most of the Mode-Mouse keys invoke functions that act on the entire window or buffer. Clicking in the echo line - the line at the bottom of the screen where prompts and message appear - results in an Echo-Mouse key. Whatever command is bound to that button will be executed. Since the echo line is not part of a buffer or a window, all the functions bound to Echo-Mouse keys affect the state of the editor as a whole. The default bindings for the hot mouse (as distributed) are: Qualifiers | Area clicked | C A Shift | Text window Mode line Echo line -------------+--------------------------------------------------------- | dot to mouse forward page switch to other buffer X | recenter backward page kill buffer X | delete word split window describe key X X | kill line delete window describe bindings X | delete char goto bob suspend MG X X | delete whitespace goto eob quit X X | kill region enlarge window list buffers X X X | yank shrink window toggle Intuition window To help keep straight what the various keys do, notice that the Status and Echo groups come in pairs; the shifted version of a key is in some sense the opposite of the unshifted version. There is no opposite for display-buffers, so that key is bound to "amiga-toggle-border", which toggles MG' Intuition window between bordered and borderless. Like any MG key, you are free to rebind the 24 mouse buttons to do whatever you wish. You may even rebind them in your startup sequence. NOTE: only functions that start with the prefix "mouse-" are able to handle clicks in windows and mode lines, because they know how to figure out where the mouse was clicked. Conversely, any non-mouse function may be bound to an Echo-Mouse key, because clicking in the echo area does not send the x,y click information to the function. If the iconification code is compiled in, then Echo-Mouse is bound to ``amiga-iconify'' by default. THE KEYBOARD ------------ There is a shortcut for many of the Meta commands (usually indicated by the ESC character): hold down the ALT key at the same time you type what usually comes after the ESC. Historically, this is why keys that are typed with ESC in front of them are called META keys; on the terminals at MIT where the Emacs editor (MG's spiritual parent) was originally written, there was a META key on the keyboard that did what the ALT key does. However, not many terminals outside of MIT have the META key at all, so the ESC key was nominated as a way to tell the system that the next character should be converted into a META key before it is interpreted. MG also recognizes Amiga function keys. For quick help on a key, type the HELP key and then the key you want help on. The following commands are bound to the Amiga function keys: Key Function -------------------------------------------- Help describe-key-briefly Left backward-char Shift-Left backward-word Right forward-char Shift-Right forward-word Up previous-line Shift-Up backward-paragraph Down next-line Shift-Down forward-paragraph F1 find-file Shift-F1 find-file-other-window F2 save-buffer Shift-F2 write-file F3 scroll-up (page down) Shift-F3 scroll-down (page up) F4 enlarge-window Shift-F4 shrink-window F5 fill-paragraph Shift-F5 query-replace F6 split-window-vertically Shift-F6 delete-other-windows F7 transpose-chars Shift-F7 just-one-space F8 start-kbd-macro Shift-F8 end-kbd-macro F9 call-last-kbd-macro Shift-F9 describe-bindings F10 list-buffers Shift-F10 save-buffers-kill-emacs FUNCTION KEY NAMES ------------------ On the Amiga, all the function keys are readily visible on the keyboard, so this table of key names for use in strings is fairly self-explanitory. If you want to rebind Shift-Down-Arrow to scroll-up (move down a whole page), for example, insert the line global-set-key "\F5" scroll-up in your s:mg-startup file. Amiga key Startup name ------------------------------------------------------------------------- Up-Arrow \F0 Down-Arrow \F1 Left-Arrow \F2 Right-Arrow \F3 Shift-Up-Arrow \F4 Shift-Down-Arrow \F5 Shift-Left-Arrow \F6 Shift-Right-Arrow \F7 Help \F9 F1 \F12 F2 \F13 F3 \F14 F4 \F15 F5 \F16 F6 \F17 F7 \F18 F8 \F19 F9 \F20 F10 \F21 Shift-F1 \F22 Shift-F2 \F23 Shift-F3 \F24 Shift-F4 \F25 Shift-F5 \F26 Shift-F6 \F27 Shift-F7 \F28 Shift-F8 \F29 Shift-F9 \F30 Shift-F10 \F31 Mouse \F32 Ctrl-Mouse \F33 Shift-Mouse \F34 Shift-Ctrl-Mouse \F35 Meta-Mouse \F36 Meta-Ctrl-Mouse \F37 Meta-Shift-Mouse \F38 Meta-Shift-Ctrl-Mouse \F39 Mode-Mouse \F40 Ctrl-Mode-Mouse \F41 Shift-Mode-Mouse \F42 Shift-Ctrl-Mode-Mouse \F43 Meta-Mode-Mouse \F44 Meta-Ctrl-Mode-Mouse \F45 Meta-Shift-Mode-Mouse \F46 Meta-Shift-Ctrl-Mode-Mouse \F47 Echo-Mouse \F48 Ctrl-Echo-Mouse \F49 Shift-Echo-Mouse \F50 Shift-Ctrl-Echo-Mouse \F51 Meta-Echo-Mouse \F52 Meta-Ctrl-Echo-Mouse \F53 Meta-Shift-Echo-Mouse \F54 Meta-Shift-Ctrl-Echo-Mouse \F55 THE MENU -------- If the menu option is compiled into the program, you can also use the Intuition menu, just like any other well-written Amiga program. The menu names are relatively self-explanitory, as are the names inside each menu. If you want to learn what the command key is for a menu function, use the command "apropos" (invoked by Ctrl-Backspace a), followed by a substring of the menu item you're curious about. THE BROWSER ----------- The Browser is the next best (or even better, for some purposes) thing to a file requester. Simply put, it places the directory tree up in the menu bar, where you can visit files simply by selecting their names from the menu bar. Try it, you'll like it. If the MENU option is also compiled in, the editing menus are all submenus of the first, "Edit" menu, and the Browser uses the rest of the menu bar. WINDOW OPTIONS -------------- As a service to those of us who want a full-size, 80-column editing window on a 640x200 screen, Amiga MG allows you to make its window borderless. If you like, you can take over the full Workbench screen (48 rows, 80 columns in interlace mode under 1.2). Borderless windows can be "visually confusing", to quote the author of Intuition, so it's probably best to either to 1) take over the whole screen or 2) put the MG window at the bottom of the screen. When Amiga MG starts up on a 640x200 screen, its initial window is borderless, and 640x200 pixels in dimension. To change to a resizeable window, issue the command "M-x amiga-toggle-border" or select the "Toggle Window" subitem from the "Window" menu (if it is compiled into the program). MG will create a new, resizeable, bordered window, which you can then set to whatever size you wish using the sizing gadget in the bottom left corner of the window. To go back to a borderless window, issue the "Toggle Window" command again. MG will remember the current size of the resizeable window, and create a borderless window with the same dimensions and position. Since under Workbench 1.2 you can use a 640x400 window, this lets you take up the entire screen, 48 rows by 80 columns. If you use MoreRows, MG will open up a resizeable window if there's enough room on the screen for an 24 line by 80 column window. CHANGING THE WINDOW'S FONT -------------------------- There may be times when you'd like to use another font on the screen, either to make the text easier to read, or for some special effect, like editing something on a TV projection system. MG lets you change the font that is used to draw characters in the window, using the command "M-x amiga-set-font". You can use the universal argument to set the desired text font size, for example saying "C-u 12 M-x set-font", then typing "opal" when it prompts you for the name of the font. If you give an argument that is less than 0, MG resets the window's font to the system default (set by Preferences). If you don't give an argument, MG prompts you for the desired font size. Changing the window's font to one that is designed to be proportionally spaced does not work very well, because MG expects the all characters on the screen to be the same width, which is of course not the case with proportional fonts. MG lets you use proportional fonts, but it asks you to make sure first. TEXT RENDITION -------------- If you really want to, you can change the "soft style" the console device uses to draw characters in the text area and the mode line. The possible values for these styles are: 0 plain 1 boldface 3 italic 4 underline 7 inverse About the only useful values are the ones for plain, boldface or italics. The default value for text is 0 (plain, of course), while the default for the mode line is 7 (inverse video). These can be changed by the appropriate #definitions of MODE_RENDITION and TEXT_RENDITION. The commands to change the rendition values are: amiga-text-rendition Set text area rendition amiga-mode-rendition Set mode line rendition (this is by far the more useful) COLOR ----- You can set the colors the console device uses to draw the text you are editing. (This does not mean that you can specify *any* color; your choices are limited to the colors being used by Intuition to maintain the Workbench screen.) The commands that control this behavior are: amiga-text-foreground Sets the color used to draw the characters you see in the text area (distinct from the mode line area for each window). Accepts a number from 0 to 7. The value initially used is 1. You can get a reverse video screen by selecting 0 for this value and 1 for the background color amiga-text-background Sets the color used the draw the background behind characters in the text area. Accepts the same values as amiga-text-foreground. The initial value is 0. amiga-mode-foreground Sets the foreground color used by the mode line. If you set this to 0 and the background color to 1, you can get a reverse video mode line even when you select italics for the mode line rendition (see RENDITION) amiga-mode-background Sets the background color for the mode line. You should get the idea by now. ICONIFICATION ------------- Leo Schwab wrote a set of very general routines for allowing an Amiga program to shrink its window to an icon. This icon can then be moved around on the screen, and re-expanded to its full size by a double click, like the one used to open a drawer. Amiga MG2a provides this capability through the function ``amiga-iconify'', which is bound to Echo-Mouse by default if the iconification code is present. Not only is this a great way to prevent screen clutter, but it also frees 50K of CHIP RAM while MG's window is iconified (on a 30 line by 80 column mg window). To iconify the window, click the mouse in MG's echo line or issue the extended command ``amiga-iconify.'' To expand MG's window back to its full size, double-click on the MG2a icon in the same way you would on a disk or drawer icon. The icon can also be dragged about, and will remember its last position when the window is iconified again. REXX ---- ARexx is a commercial product that provides an extension language - a macro facility - to Amiga programs for very little overhead. It also allows communications between programs that know nothing of each other. It will be bundled with AmigaDOS version 2.0, so everyone should have it in the near future. The Amiga version of mg3 has some functions specifically to support Rexx. They allow for the creation of some very powerfull mg scripts, including the creation of integrated programming environments for most compiled languages, and of the ability to dynamically test functions from inside the editor for intrepreted languages. The mg3 Rexx support functions are documented below; see the Rexx directory for examples using this functionality. Rexx macros can be invoked from mg in one of two ways. The first way is close to the "standard rexx" interface. The second provides much more flexibility and power to the user. Finally, you can arrange for a rexx macro to be invoked on exiting from mg (for cleanup, or whatever). The first way is the "rexx" command. This reads a single argument from the user, and is passed to ARexx as a command. If the string is quoted, ARexx will execute it as a "string macro", interpreting the contents. If it's not quoted, the first token of the string is taken to be a command name. That command is searched for, with either no extension, or the extension "mg". If found, the file will be invoked, with any text after the command name arranged as the argument to the command. Alternatively, if the Rexx command is invoked with a universal argument, the rest of the string will tokenized by rexx. This allows for arguments that can't normally be passed. For example, to pass a null argument, you would do: C-u M-x rexx C-m macroname "" C-m. There's no way to pass a null argument without invoking tokenization. Rexx should be the standard way of invoking rexx macros. Note that having all unrecognized commands passed to rexx doesn't work in mg, as it tries to complete command names. Doing this right would require more code than is justified in a micro emacs. However, you can use named kbd macros to invoke rexx macros, thus putting rexx commands into the standard command set. In addition, you can also use command completion on those macro names. The second, and more powerful technic is "rexx-do-region". This passes the contents of the region to ARexx as a string macro, invoking it as a function. The numeric argument to rexx-do-string controls it's behavior in two ways. If the argument doesn't exist, or is positive, the result string returned by the macro is displayed in the echo line. If the argument is zero or negative, then the result string from the macro is inserted into the buffer at the point. If it's given an argument, then the absolute magnitude of the argument is the number of argument strings to be passed to the macro. The user is asked for these one at a time, and they are then made available to the macro via the normal argument mechanisms. Due to overloading of the argument, there is no way to invoke a macro with no arguments and have it's returned value inserted into the buffer. A typical use for this would be to mark a Rexx procedure definition, then use rexx-do-region to pass the function and any arguments to Rexx for evaluation from inside of mg. Writing the function to disk is not required, nor is writing a skeleton to invoke the function for testing. You can also use "rexx-do-on-exit". It takes a string in exactly the same way that "rexx" does, however, it doesn't do any of the argument processing that the "rexx" command does. This is for cleaning up on exit from mg. Finally, "rexx-wait" causes mg to close it's window and wait for a message to it's Rexx port. This is useful for uncluttering your workbench and freeing chip memory. The companion function "amiga-window-to-top" is usefull for opening an mg doing a rexx-wait. When ARexx code is run from mg, any commands issued by the Rexx interpreter are evaluated as expressions by mg. Thus, all commands normally available to the user are available from Rexx code. However, the tokenization must be kept in mind when writing Rexx macros. For example, to search for the text string "the word", one should use: 'search "the word"', not 'search the word'. In addition, most of the mg commands are of the form 'list-of-words', with embedded '-''s. Since ARexx recognizes these as operators outside of strings, most commands should be embedded in quotes of some form or another. It's a good practice to put all commands in quotes, regardless of whether they need it or not. In fact, This is true for all Rexx command hosts, not just mg. Mg commands offer only four return values: 0 - completed normally 1 - error, such as moving past the end of the file 2 - failure, such as a user abort or command parse error 3 - locked, this mg isn't currently accepting asynch macros 4 - this mg doesn't do Rexx messages at all Macros should always abort on a return of 2. A return of 1 can be used for flow control, or ignored. In addition to the commands normally available, ARexx support in mg has commands added that allow the user to query the editor for data, and modify it. All of these start with "rexx-", to avoid removing otherwise useful names from the namespace. None of these commands may be invoked except from a Rexx script. rexx-insert takes a single argument, and inserts it into the current buffer at the point. Note that that argument must be a valid argument by mg expression evaluation criteria, not by Rexx's. So to insert the value of the variable addstuff, one should do something like: 'rexx-insert' '"'addstuff'"' to be safe. To be very safe, and somewhat shorter, you should always invoke rexx-insert as 'rexx-insert "', and end it with '"'. Also note that '"' and '\' get special treatment, and must be preceeded by a '\' to be inserted safely. The file rexx/slashquote returns a single string that is the "rexx-insertable" version of it's argument, so the above would be: 'rexx-insert' '"'slashquote(addstuff)'"' to be absolutly safe. Other rexx-specific functions that take a single string argument are: rexx-display: instead of inserting it's argument into the buffer, this command displays it for the user. There are also commands to get information from the user. They all take a message like rexx-display, and display it as a prompt in the echo area. They then read a string from the user, and return it as their result. They are: rexx-request gets an arbitrary string. rexx-request-buffer gets a buffer name, with completion. rexx-request-function gets a function or kbd macro name, with completion. rexx-request-macro gets a kbd macro name, with completion. Aborts or errors during the reads are passed on to the Rexx macro. rexx-line also returns data via result. It returns the contents of a single line of text from the current buffer, sans any trailing newline. It's numeric argument is the line number to be returned. Negative arguments count backwards from the end of the buffer. If it has no argument, it returns the current line. Referring to a non-existent line is an error. Next, there is a group of routines that take a Rexx variable name as an argument, use it as the stem of a compound symbol. The format for all of them is them is the same: for n from 1 to stem.0, stem.n contains data. With one exception, there are no more levels in the compound variables. If for any reason all the stem variables the command wants to set cannot be set, an error is returned. Note that unlike XEDIT, the name of the stem is not fixed - it's the argument to the command. So "rexx-point point1" <other commands> "rexx-point point2" creates two compound variables, point1 and point2, each holding data about a point. rexx-point: stem.1 is the line number the point is on, stem.2 is the points offset into the line, stem.3 is the text of the line the point is on. rexx-mark: identical to rexx-point, except that it returns data about the mark instead of the point. If no mark exists in the current buffer, rexx.0 is set to 0, and an error is returned. rexx-buffer: stem.1 is the buffer name, stem.2 is the file name associated with the buffer, stem.3 is the number of lines in the buffer, stem.4 is the number of characters in the buffer, stem.5 is the line # the point is on, stem.6 is the line # the mark is on. If no mark exists, stem.6 is not set, stem.0 will be 5, and an error will be returned. If no file is associated with the buffer, the stem.2 will be "", and no error will be signaled. rexx-window: stem.1 is the height of the current window in characters, stem.2 is it's width, stem.3 is the number of the top line in the window, stem.4 is the name of the displayed buffer, stem.5 is the name of the file in that buffer. If there is no buffer name (which should never happen), then stem.0 will be 3, and an error will be returned. rexx-region returns the text of the region. If no mark is set (hence no region), stem.0 is set to 0, and an error is returned. The text of each line is returned in stem.#, with the newline (unlike rexx-line). The last line may not have a newline, if the region does not end after a newline character. rexx-buffer-list is the exception mentioned above. Instead of returning data in stem.#, these contain another level of compound variable. Stem.# contains data about a specific buffer, like so: stem.#.NAME is the name of buffer #, stem.#.FILE is the file it's editing, and stem.#.STATUS is either "" or "CHANGED " if it's been changed, with "CURRENT" appended if this is the current buffer. Finally, there are two commands that allow Rexx macros to issue commands to mg asynchronously. When a rexx macro is started, mg is locked, meaning that only Rexx commands from that macro will be processed. Any other will return an error code 3. That macro may unlock mg, allowing the user to issue mg commands from the keyboard. After unlocking mg, the macro may continue to issue commands to mg, and even relock mg. Further, any Rexx script, no matter what client it was started from, may issue commands to an unlocked mg, and lock it. The two commands are: rexx-unlock unlocks the current mg, allowing other macros and the user to enter commands to it. It returns the value of the address for asynch commands to this mg as a result. rexx-lock locks the current mg, so that mg only accepts commands from the locking macro. It returns the address to use for the commands as a result. If called without the results option being on, it has no affect. If you call rexx-lock to lock an mg, you must call rexx-unlock to free it. Otherwise, the mg will be hung, waiting for a packet from that macro that it will never get. Typical useage of the above two might be: options results /* Get all information we need, and verify it */ /* Free ourselves */ 'rexx-unlock' address value result /* Do much computing; the user is free to use the editor */ /* Get back in synch */ 'rexx-lock' address value result 'rexx-display "Computation finished, inserting into My_Buffer"' /* Do the insert */ When mg is first started, it tries to open a public port named "mg". If that fails, it tries 'mg!', and then 'mg"', and so on through 'mg~', then to 'mg!!', 'mg"!', and so through the ASCII character set, up to "mg~~". Sending 'rexx-lock' commands to those port names until one succeeds is the best way to find and lock an mg. FUNCTION LIST ------------- For completeness, here is a list of all Amiga MG functions that are specific to the Amiga. amiga-iconify Iconifies the Amiga MG window. amiga-menu The entry point for using MG's Intuition menu. This function figures out which menu selection was used, then calls the appropriate function by name (not hard-coded key value) amiga-mouse Set dot to where the mouse is pointing. Two clicks in the same spot set the mark too. mouse-* Functions that first either 1) move point to where the mouse points to or 2) select the buffer associated with the mode line the mouse clicked in, then call the function indicated by the rest of the name. These functions are all "bound" to various mouse click keys. amiga-set-font Set the font used to draw characters inside the MG window. A positive argument is used for the size of the font, while a nonpositive argument requests that the font be set to the system default font. Menu items are not affected by this command. amiga-mode-rendition amiga-text-rendition Set the way your text (or the mode line) is rendered. Choose from 0 (plain), 1 (bold), 3 (italic), 4 (underline), or 7 (reverse video). 0, 1, and 3 are about the only really useful ones for text; 7 is the default for the mode line. amiga-text-foreground amiga-text-background amiga-mode-foreground amiga-mode-background Set the system color used to draw the characters in the text area and mode line. Accepts a value between 0 and 7; the default for the background is 0, the default for the text is 1. amiga-toggle-border Switch your window between resizable and borderless. Lets you take over the whole screen (80 columns! 48 lines in interlace!) amiga-window-to-top Only defined if REXX is enabled. Causes mg3 to bring it's window and screen to the top of the screen. rexx Send a command to rexx. rexx-wait Close the window, and reopen it on reciept of a Rexx message rexx-do-on-exit Arrange for a rexx command to be issued when mg exits. rexx-do-region Send the current region to rexx as a string macro. rexx-buffer rexx-buffer-list rexx-display rexx-insert rexx-line rexx-lock rexx-mark rexx-point rexx-region rexx-request rexx-request-buffer rexx-request-function rexx-request-macro rexx-unlock rexx-window Only issueable from inside of a Rexx script. See the section on Rexx for details.